29 أغسطس 2025العربية

أتقن خطاف useFormStatus في React للتعامل السلس مع إرسال النماذج، وتتبع التقدم، وتحسين تجربة المستخدم. تعلم كيفية بناء نماذج قوية وسهلة الاستخدام.

خطاف useFormStatus في React: دليل شامل لحالة إرسال النماذج وتتبع التقدم

تشكل النماذج العمود الفقري لعدد لا يحصى من تطبيقات الويب، حيث تعمل كواجهة أساسية لتفاعل المستخدم. ومع ذلك، يمكن أن تكون إدارة عمليات إرسال النماذج، والتعامل مع الأخطاء، وتقديم الملاحظات للمستخدمين مهمة معقدة. يبسط خطاف useFormStatus من React هذه العملية، حيث يقدم طريقة مبسطة لتتبع حالة إرسال النموذج وتوفير تجربة مستخدم أكثر سهولة.

ما هو `useFormStatus`؟

تم تقديمه في React 18، useFormStatus هو خطاف مصمم لتوفير معلومات حول حالة إرسال عنصر <form>. يسمح لك بتحديد ما إذا كان النموذج قيد الإرسال حاليًا، أو تم إرساله بنجاح، أو واجه خطأ أثناء الإرسال. يمكن استخدام هذه المعلومات لتحديث واجهة المستخدم، أو تعطيل الأزرار، أو عرض مؤشرات التحميل، أو تقديم رسائل خطأ للمستخدم.

الفوائد الرئيسية لاستخدام `useFormStatus`:

إدارة مبسطة لحالة النموذج: يلغي الحاجة إلى الإدارة اليدوية للحالة عند إرسال النموذج، مما يقلل من التعليمات البرمجية المكررة.
تجربة مستخدم محسّنة: يوفر ملاحظات فورية للمستخدمين أثناء إرسال النموذج، مما يعزز سهولة الاستخدام.
إمكانية وصول محسّنة: يسمح بتفاعلات نماذج يسهل الوصول إليها عن طريق تعطيل عناصر النموذج أثناء الإرسال وتوفير رسائل خطأ واضحة.
أداء محسن: يتتبع حالة إرسال النموذج بكفاءة، مما يمنع إعادة العرض غير الضرورية.

كيف يعمل `useFormStatus`

يتم استخدام خطاف useFormStatus داخل مكون React الذي يعرض عنصر <form>. يعيد الخطاف كائنًا يحتوي على الخصائص التالية:

pending: قيمة منطقية (boolean) تشير إلى ما إذا كان النموذج قيد الإرسال حاليًا.
data: البيانات التي تم إرجاعها بواسطة دالة الإجراء (action) الخاصة بالنموذج (في حالة النجاح).
method: طريقة HTTP المستخدمة لإرسال النموذج (على سبيل المثال، "POST"، "GET").
action: الدالة التي تم استدعاؤها عند إرسال النموذج.
error: كائن خطأ إذا فشل إرسال النموذج.

لاستخدام useFormStatus، تحتاج أولاً إلى تحديد دالة action لنموذجك. سيتم استدعاء هذه الدالة عند إرسال النموذج. داخل دالة action، يمكنك إجراء أي معالجة بيانات ضرورية أو التحقق من الصحة أو استدعاءات API. يجب أن تعيد دالة action قيمة ستكون متاحة في خاصية data لخطاف useFormStatus. إذا أثارت الدالة خطأً، فسيكون هذا الخطأ متاحًا في خاصية error.

أمثلة عملية على `useFormStatus`

مثال 1: تتبع إرسال النموذج الأساسي

يوضح هذا المثال كيفية استخدام useFormStatus لتتبع حالة إرسال نموذج اتصال بسيط. يعمل هذا المثال في مكون خادم React (RSC)، والذي يتطلب إطار عمل مثل Next.js أو Remix.


// app/contact/page.tsx (Next.js)
'use client';

import { useFormStatus } from 'react-dom';

async function submitForm(formData: FormData) {
  "use server";
  // محاكاة استدعاء واجهة برمجة التطبيقات (API)
  await new Promise((resolve) => setTimeout(resolve, 2000));

  const name = formData.get('name') as string;
  const email = formData.get('email') as string;
  const message = formData.get('message') as string;

  if (!name || !email || !message) {
    throw new Error('Please fill in all fields.');
  }

  console.log('Form Data:', { name, email, message });
  return { message: 'Form submitted successfully!' };
}

export default function ContactForm() {
  const { pending, data, error } = useFormStatus();

  return (
    
      الاسم:
      


      البريد الإلكتروني:
      


      الرسالة:
      


      

      {data && {data.message}}
      {error && خطأ: {error.message}}
    
  );
}

في هذا المثال، يتم استخدام حالة pending لتعطيل مدخلات النموذج وزر الإرسال أثناء إرسال النموذج. كما أنه يغير نص الزر ديناميكيًا إلى "جاري الإرسال..." لتقديم ملاحظات مرئية للمستخدم. عند النجاح، يتم عرض data من إجراء submitForm. إذا حدث خطأ أثناء الإرسال، يتم عرض رسالة error للمستخدم.

مثال 2: عرض مؤشر التحميل

يوضح هذا المثال كيفية عرض مؤشر تحميل أثناء إرسال النموذج. هذا مفيد بشكل خاص للنماذج التي تتضمن استدعاءات API طويلة أو معالجة بيانات معقدة.


// بنية مكون مشابهة للمثال 1
export default function ContactForm() {
  const { pending, data, error } = useFormStatus();

  return (
    
      {/* ... مدخلات النموذج ... */}

      

      {pending && جاري التحميل...} {/* إظهار مؤشر التحميل */}

      {data && {data.message}}
      {error && خطأ: {error.message}}
    
  );
}

في هذا المثال، يتم عرض رسالة بسيطة "جاري التحميل..." عندما تكون حالة pending صحيحة. يمكنك استبدال هذا بمؤشر تحميل أكثر تطوراً، مثل دائرة دوارة أو شريط تقدم.

مثال 3: التعامل مع أخطاء التحقق من صحة النموذج

يوضح هذا المثال كيفية التعامل مع أخطاء التحقق من صحة النموذج باستخدام useFormStatus. تقوم دالة action بالتحقق من الصحة وتلقي خطأ إذا تم انتهاك أي من قواعد التحقق.


// بنية مكون مشابهة للمثال 1
async function submitForm(formData: FormData) {
  "use server";
  const name = formData.get('name') as string;
  const email = formData.get('email') as string;
  const message = formData.get('message') as string;

  if (!name) {
    throw new Error('الاسم مطلوب.');
  }
  if (!email) {
    throw new Error('البريد الإلكتروني مطلوب.');
  }
  if (!message) {
    throw new Error('الرسالة مطلوبة.');
  }

  // محاكاة استدعاء واجهة برمجة التطبيقات (API)
  await new Promise((resolve) => setTimeout(resolve, 2000));

  console.log('Form Data:', { name, email, message });
  return { message: 'Form submitted successfully!' };
}

export default function ContactForm() {
  const { pending, data, error } = useFormStatus();

  return (
    
      {/* ... مدخلات النموذج ... */}

      

      {error && خطأ: {error.message}} {/* عرض رسالة الخطأ */}
    
  );
}

في هذا المثال، تتحقق دالة action مما إذا كانت حقول الاسم والبريد الإلكتروني والرسالة فارغة. إذا كان أي من هذه الحقول فارغًا، فإنها تلقي خطأً برسالة مقابلة. يتم بعد ذلك استخدام خاصية error لخطاف useFormStatus لعرض رسالة الخطأ للمستخدم.

حالات الاستخدام المتقدمة والاعتبارات

التكامل مع مكتبات النماذج الخارجية

بينما يوفر useFormStatus حلاً أصليًا لتتبع حالة إرسال النموذج، يمكن أيضًا دمجه مع مكتبات نماذج خارجية مثل Formik أو React Hook Form. توفر هذه المكتبات ميزات أكثر تقدمًا مثل التحقق من صحة النموذج، وإدارة الحقول، وإدارة الحالة. من خلال الجمع بين useFormStatus وهذه المكتبات، يمكنك إنشاء نماذج قابلة للتخصيص بدرجة عالية وقوية.

للتكامل مع Formik أو React Hook Form، يمكنك الاستفادة من معالجات إرسال النماذج الخاصة بكل منهما واستخدام useFormStatus لتتبع حالة الإرسال الإجمالية. من المحتمل أنك ستظل بحاجة إلى إنشاء إجراء خادم (Server Action)، ولكن إدارة حالة النموذج من جانب العميل ستتم معالجتها بواسطة المكتبة المختارة.

التعامل مع العمليات غير المتزامنة

تتضمن العديد من النماذج عمليات غير متزامنة مثل استدعاءات API أو استعلامات قاعدة البيانات. عند التعامل مع العمليات غير المتزامنة، من المهم التأكد من معالجة إرسال النموذج بشكل صحيح وتزويد المستخدم بالملاحظات المناسبة. يبسط خطاف useFormStatus هذه العملية من خلال توفير حالة pending يمكن استخدامها للإشارة إلى أن النموذج ينتظر اكتمال عملية غير متزامنة.

من الضروري أيضًا تنفيذ معالجة قوية للأخطاء للتعامل بأمان مع أي أخطاء قد تحدث أثناء العمليات غير المتزامنة. يمكن استخدام خاصية error لخطاف useFormStatus لعرض رسائل الخطأ للمستخدم.

اعتبارات إمكانية الوصول

تعد إمكانية الوصول جانبًا حاسمًا في تطوير الويب، والنماذج ليست استثناءً. عند بناء النماذج، من المهم التأكد من أنها متاحة للمستخدمين ذوي الإعاقة. يمكن استخدام خطاف useFormStatus لتعزيز إمكانية الوصول إلى النماذج عن طريق:

تعطيل عناصر النموذج أثناء الإرسال: هذا يمنع المستخدمين من إرسال النموذج عن طريق الخطأ عدة مرات.
توفير رسائل خطأ واضحة: يجب أن تكون رسائل الخطأ موجزة وغنية بالمعلومات وسهلة الفهم. يجب أيضًا ربطها بحقول النموذج المقابلة باستخدام سمات ARIA.
استخدام سمات ARIA: يمكن استخدام سمات ARIA لتوفير معلومات إضافية حول النموذج وعناصره للتقنيات المساعدة. على سبيل المثال، يمكن استخدام سمة aria-describedby لربط رسائل الخطأ بحقول النموذج.

تحسين الأداء

بينما يكون useFormStatus فعالاً بشكل عام، من المهم مراعاة الآثار المترتبة على الأداء عند بناء نماذج معقدة. تجنب إجراء حسابات مكلفة أو استدعاءات API داخل المكون الذي يستخدم useFormStatus. بدلاً من ذلك، قم بتفويض هذه المهام إلى دالة action.

أيضًا، كن على دراية بإعادة العرض غير الضرورية. استخدم تقنيات الحفظ المؤقت (memoization) في React (مثل React.memo، useMemo، useCallback) لمنع المكونات من إعادة العرض ما لم تتغير خصائصها.

أفضل الممارسات لاستخدام `useFormStatus`

حافظ على دالات action الخاصة بك موجزة ومركزة: يجب أن تتعامل دالة action بشكل أساسي مع معالجة البيانات والتحقق من الصحة واستدعاءات API. تجنب إجراء تحديثات معقدة لواجهة المستخدم أو أي آثار جانبية أخرى داخل دالة action.
قدم ملاحظات واضحة وغنية بالمعلومات للمستخدمين: استخدم خصائص pending و data و error لخطاف useFormStatus لتقديم ملاحظات فورية للمستخدمين أثناء إرسال النموذج.
نفّذ معالجة قوية للأخطاء: تعامل بأمان مع أي أخطاء قد تحدث أثناء إرسال النموذج وقدم رسائل خطأ غنية بالمعلومات للمستخدم.
ضع في اعتبارك إمكانية الوصول: تأكد من أن نماذجك متاحة للمستخدمين ذوي الإعاقة باتباع أفضل ممارسات إمكانية الوصول.
حسّن الأداء: تجنب إعادة العرض غير الضرورية والحسابات المكلفة داخل المكون الذي يستخدم useFormStatus.

تطبيقات وأمثلة من العالم الحقيقي من جميع أنحاء العالم

يمكن تطبيق خطاف useFormStatus على سيناريوهات مختلفة قائمة على النماذج عبر مختلف الصناعات والمواقع الجغرافية. إليك بعض الأمثلة:

التجارة الإلكترونية (عالميًا): يمكن لمتجر عبر الإنترنت استخدام useFormStatus لتتبع إرسال نماذج الطلبات. يمكن استخدام حالة pending لتعطيل زر "إتمام الطلب" أثناء معالجة الطلب، ويمكن استخدام حالة error لعرض رسائل الخطأ إذا فشل إرسال الطلب (على سبيل المثال، بسبب مشكلات في الدفع أو نقص في المخزون).
الرعاية الصحية (أوروبا): يمكن لمقدم الرعاية الصحية استخدام useFormStatus لتتبع إرسال نماذج تسجيل المرضى. يمكن استخدام حالة pending لعرض مؤشر تحميل أثناء معالجة معلومات المريض، ويمكن استخدام حالة data لعرض رسالة تأكيد عند التسجيل بنجاح. يعد الامتثال للائحة العامة لحماية البيانات (GDPR) أمرًا بالغ الأهمية، ويجب التعامل بعناية مع رسائل الخطأ المتعلقة بانتهاكات خصوصية البيانات.
التعليم (آسيا): يمكن لمنصة تعليمية عبر الإنترنت استخدام useFormStatus لتتبع إرسال تحميلات الواجبات. يمكن استخدام حالة pending لتعطيل زر "إرسال" أثناء تحميل الواجب، ويمكن استخدام حالة error لعرض رسائل الخطأ إذا فشل التحميل (على سبيل المثال، بسبب قيود حجم الملف أو مشكلات الشبكة). قد يكون لدى البلدان المختلفة معايير أكاديمية ومتطلبات إرسال مختلفة، والتي يجب أن يستوعبها النموذج.
الخدمات المالية (أمريكا الشمالية): يمكن للبنك استخدام useFormStatus لتتبع إرسال نماذج طلبات القروض. يمكن استخدام حالة pending لعرض مؤشر تحميل أثناء معالجة الطلب، ويمكن استخدام حالة data لعرض حالة الموافقة على القرض. يعد الامتثال للوائح المالية (مثل KYC - اعرف عميلك) أمرًا بالغ الأهمية، ويجب أن تكون رسائل الخطأ المتعلقة بقضايا الامتثال واضحة ومحددة.
الخدمات الحكومية (أمريكا الجنوبية): يمكن لوكالة حكومية استخدام useFormStatus لتتبع إرسال نماذج ملاحظات المواطنين. يمكن استخدام حالة pending لتعطيل زر "إرسال" أثناء معالجة الملاحظات، ويمكن استخدام حالة data لعرض رسالة تأكيد عند الإرسال بنجاح. تعد إمكانية الوصول أمرًا بالغ الأهمية، حيث قد يكون لدى المواطنين مستويات متفاوتة من المعرفة الرقمية والوصول إلى التكنولوجيا. يجب أن يكون النموذج متاحًا بلغات متعددة.

استكشاف الأخطاء الشائعة وإصلاحها

useFormStatus لا يتم تحديثه: تأكد من أنك تستخدم React 18 أو إصدارًا أحدث وأن نموذجك يحتوي على action محدد بشكل صحيح. تحقق من أن إجراء الخادم (Server Action) الخاص بك محدد بشكل صحيح باستخدام التوجيه "use server".
رسائل الخطأ لا تظهر: تحقق جيدًا من أن دالة action الخاصة بك تلقي الأخطاء بشكل صحيح وأنك تعرض error.message في مكونك. افحص وحدة التحكم بحثًا عن أي أخطاء أثناء إرسال النموذج.
النموذج يرسل عدة مرات: تأكد من تعطيل زر الإرسال باستخدام حالة pending لمنع النقرات المزدوجة العرضية.

الخاتمة

يوفر خطاف useFormStatus من React طريقة قوية ومريحة لتتبع حالة إرسال النموذج وتوفير تجربة مستخدم أفضل. من خلال تبسيط إدارة حالة النموذج، وتعزيز إمكانية الوصول، وتحسين الأداء، يمكّن useFormStatus المطورين من بناء نماذج قوية وسهلة الاستخدام. من خلال فهم قدراته وأفضل الممارسات، يمكنك الاستفادة من useFormStatus لإنشاء تفاعلات نماذج سلسة وجذابة في تطبيقات React الخاصة بك.